home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 July: Mac OS SDK / Dev.CD Jul 00 SDK2.toast / Development Kits / Cross Platform / QuickTime 4.1.2 Windows SDK / CIncludes / CarbonEvents.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-04-12  |  42.5 KB  |  1,288 lines  |  [TEXT/R*ch]
  1. /*
  2.      File:        CarbonEvents.h
  3.  
  4.      Contains:    Carbon Event Manager
  5.  
  6.      Version:    Technology:    Version 1.0
  7.                  Release:    QuickTime 4.1
  8.  
  9.      Copyright:    (c) 1999 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. */
  17. #ifndef __CARBONEVENTS__
  18. #define __CARBONEVENTS__
  19.  
  20. #ifndef __EVENTS__
  21.     #include <Events.h>
  22. #endif
  23.  
  24. #ifndef __MENUS__
  25.     #include <Menus.h>
  26. #endif
  27.  
  28. #ifndef __CONTROLS__
  29.     #include <Controls.h>
  30. #endif
  31.  
  32.  
  33.  
  34.  
  35. #if PRAGMA_ONCE
  36. #pragma once
  37. #endif
  38.  
  39. #ifdef __cplusplus
  40. extern "C" {
  41. #endif
  42.  
  43. #if PRAGMA_IMPORT
  44. #pragma import on
  45. #endif
  46.  
  47. #if PRAGMA_STRUCT_ALIGN
  48.     #pragma options align=mac68k
  49. #elif PRAGMA_STRUCT_PACKPUSH
  50.     #pragma pack(push, 2)
  51. #elif PRAGMA_STRUCT_PACK
  52.     #pragma pack(2)
  53. #endif
  54.  
  55. /*======================================================================================*/
  56. /*    EVENT COMMON                                                                        */
  57. /*======================================================================================*/
  58.  
  59.  
  60. enum {
  61.     eventAlreadyPostedErr        = -9860,
  62.     eventClassInvalidErr        = -9862,
  63.     eventClassAlreadyExistsErr    = -9863,
  64.     eventClassIncorrectErr        = -9864,
  65.     eventClassInvalidVersionErr    = -9865,
  66.     eventHandlerAlreadyInstalledErr = -9866,
  67.     eventCantInstallHandlerErr    = -9867,
  68.     eventInternalErr            = -9868,
  69.     eventKindIncorrectErr        = -9869,
  70.     eventDataTagNotSupportedErr    = -9870,
  71.     eventDataSizeMismatchErr    = -9871
  72. };
  73.  
  74. /*======================================================================================*/
  75. /*    EVENT CORE                                                                            */
  76. /*======================================================================================*/
  77. /*--------------------------------------------------------------------------------------*/
  78. /*    o Event Flags, options                                                                */
  79. /*--------------------------------------------------------------------------------------*/
  80.  
  81. typedef SInt16 EventPriority;
  82. enum {
  83.     kEventPriorityLow            = 0,
  84.     kEventPriorityStandard        = 1,
  85.     kEventPriorityHigh            = 2
  86. };
  87.  
  88.  
  89. typedef UInt32 EventAttributes;
  90. enum {
  91.     kEventAttributeNone            = 0,
  92.     kEventAttributeUserEvent    = (1 << 0),
  93.     kEventAttributeRouteToUserFocus = (1 << 1)
  94. };
  95.  
  96. enum {
  97.     kEventLeaveInQueue            = false,
  98.     kEventRemoveFromQueue        = true
  99. };
  100.  
  101. /*--------------------------------------------------------------------------------------*/
  102. /* o Event Times                                                                        */
  103. /*                                                                                        */
  104. /* EventTime is in seconds since boot. Use the constants to make life easy.             */
  105. /*--------------------------------------------------------------------------------------*/
  106. typedef double                             EventTime;
  107. typedef EventTime                         EventTimeout;
  108. typedef EventTime                         EventTimerInterval;
  109.  
  110. #define kEventDurationSecond             1.0
  111. #define kEventDurationMillisecond         kEventDurationSecond / 1000
  112. #define kEventDurationMicrosecond         kEventDurationSecond / 1000000
  113. #define kEventDurationNanosecond         kEventDurationSecond / 1000000000
  114. #define kEventDurationMinute             kEventDurationSecond * 60
  115. #define kEventDurationHour                 kEventDurationMinute * 60
  116. #define kEventDurationDay                 kEventDurationHour * 24
  117. #define kEventDurationNoWait             0.0
  118. #define kEventDurationForever             -1.0
  119.  
  120. /* Helpful doodads to convert from and to ticks from event times*/
  121. #ifdef __cplusplus
  122.     inline EventTime TicksToEventTime( UInt32 t ) { return ( (t) / 60.0 ); }
  123.     inline UInt32 EventTimeToTicks( EventTime t ) { return (UInt32)( (t) * 60 ); }
  124. #else
  125.     #define TicksToEventTime( t )    (EventTime)( (t) / 60.0 )
  126.     #define EventTimeToTicks( t )    (UInt32)( (t) * 60 )
  127. #endif  /* defined(__cplusplus) */
  128.  
  129.  
  130. /*--------------------------------------------------------------------------------------*/
  131. /* EventTypeSpec structure                                                                */
  132. /*                                                                                        */
  133. /* This structure is used in many routines to pass a list of event types to a function.    */
  134. /* You typically would declare a const array of these types to pass in.                    */
  135. /*--------------------------------------------------------------------------------------*/
  136.  
  137. struct EventTypeSpec {
  138.     UInt32                             eventClass;
  139.     UInt32                             eventKind;
  140. };
  141. typedef struct EventTypeSpec            EventTypeSpec;
  142.  
  143. /* MouseTrackingResults returned from TrackMouse*/
  144.  
  145.  
  146. typedef UInt16 MouseTrackingResult;
  147. enum {
  148.     kMouseTrackingMousePressed    = 1,
  149.     kMouseTrackingMouseReleased    = 2,
  150.     kMouseTrackingMouseExited    = 3,
  151.     kMouseTrackingMouseEntered    = 4,
  152.     kMouseTrackingMouseMoved    = 5
  153. };
  154.  
  155. typedef struct OpaqueEventRef*             EventRef;
  156.  
  157. typedef UInt32                             EventClassID;
  158. typedef UInt32                             EventClass;
  159. typedef UInt32                             EventType;
  160. /*--------------------------------------------------------------------------------------*/
  161. /*    o Low-level event blocking                                                            */
  162. /*--------------------------------------------------------------------------------------*/
  163.  
  164. EXTERN_API( Boolean )
  165. BlockUntilNextEvent                (EventTimeout             timeout,
  166.                                  Boolean                 pullEvent,
  167.                                  EventRef *                outEvent);
  168.  
  169. EXTERN_API( Boolean )
  170. BlockUntilNextEventMatchingList    (UInt32                 numTypes,
  171.                                  const EventTypeSpec *    list,
  172.                                  EventTimeout             timeout,
  173.                                  Boolean                 pullEvent,
  174.                                  EventRef *                outEvent);
  175.  
  176. /*--------------------------------------------------------------------------------------*/
  177. /*    o Core event lifetime APIs                                                            */
  178. /*--------------------------------------------------------------------------------------*/
  179.  
  180. EXTERN_API( EventRef )
  181. CopyEvent                        (EventRef                 inOther);
  182.  
  183. EXTERN_API( EventRef )
  184. RetainEvent                        (EventRef                 inEvent);
  185.  
  186. EXTERN_API( UInt32 )
  187. GetEventRetainCount                (EventRef                 inEvent);
  188.  
  189. EXTERN_API( void )
  190. ReleaseEvent                    (EventRef                 inEvent);
  191.  
  192. /*--------------------------------------------------------------------------------------*/
  193. /*    o Getters for 'base-class' event info                                                */
  194. /*--------------------------------------------------------------------------------------*/
  195.  
  196. EXTERN_API( UInt32 )
  197. GetEventClass                    (EventRef                 inEvent);
  198.  
  199. EXTERN_API( UInt32 )
  200. GetEventKind                    (EventRef                 inEvent);
  201.  
  202. EXTERN_API( EventAttributes )
  203. GetEventAttributes                (EventRef                 inEvent);
  204.  
  205. EXTERN_API( EventTime )
  206. GetEventTime                    (EventRef                 inEvent);
  207.  
  208. EXTERN_API( UInt32 )
  209. GetEventPriority                (EventRef                 inEvent);
  210.  
  211. /*--------------------------------------------------------------------------------------*/
  212. /*    o Setters for 'base-class' event info                                                */
  213. /*--------------------------------------------------------------------------------------*/
  214. EXTERN_API( OSStatus )
  215. SetEventTime                    (EventRef                 inEvent,
  216.                                  EventTime                 inTime);
  217.  
  218.  
  219. /*--------------------------------------------------------------------------------------*/
  220. /*    o Getting/setting common event data via tags                                        */
  221. /*                                                                                        */
  222. /*    NOTE: THIS STUFF IS NOT YET ACTIVE. DO NOT ATTEMPT TO USE IT.                        */
  223. /*--------------------------------------------------------------------------------------*/
  224. enum {
  225.     kEventTagKeyModifiers        = FOUR_CHAR_CODE('mods'),        /* UInt32*/
  226.     kEventTagMouseLocation        = FOUR_CHAR_CODE('mloc')        /* Point*/
  227. };
  228.  
  229. typedef UInt32                             EventDataTag;
  230. EXTERN_API( OSStatus )
  231. GetEventDataByTag                (EventRef                 inEvent,
  232.                                  EventDataTag             inKey,
  233.                                  void *                    buffer,
  234.                                  Size                     bufferSize,
  235.                                  Size *                    actualSize) /* can be NULL */;
  236.  
  237. EXTERN_API( OSStatus )
  238. SetEventDataByTag                (EventRef                 inEvent,
  239.                                  EventDataTag             inKey,
  240.                                  void *                    buffer,
  241.                                  Size                     bufferSize);
  242.  
  243. /* Common, type-safe wrappers for the above...*/
  244.  
  245. EXTERN_API( OSStatus )
  246. GetEventKeyModifiers            (EventRef                 inEvent,
  247.                                  UInt32 *                outModifiers);
  248.  
  249. EXTERN_API( OSStatus )
  250. SetEventKeyModifiers            (EventRef                 inEvent,
  251.                                  UInt32                 inModifiers);
  252.  
  253. EXTERN_API( OSStatus )
  254. GetEventMouseLocation            (EventRef                 inEvent,
  255.                                  Point *                outMouseLoc);
  256.  
  257. EXTERN_API( OSStatus )
  258. SetEventMouseLocation            (EventRef                 inEvent,
  259.                                  Point                     inMouseLoc);
  260.  
  261. /*--------------------------------------------------------------------------------------*/
  262. /*    o Event Queue routines (posting, finding, flushing)                                    */
  263. /*--------------------------------------------------------------------------------------*/
  264.  
  265. typedef CALLBACK_API( Boolean , EventComparatorProcPtr )(EventRef inEvent, void *inCompareData);
  266. typedef STACK_UPP_TYPE(EventComparatorProcPtr)                     EventComparatorUPP;
  267. #if OPAQUE_UPP_TYPES
  268.     EXTERN_API(EventComparatorUPP)
  269.     NewEventComparatorUPP           (EventComparatorProcPtr    userRoutine);
  270.  
  271.     EXTERN_API(void)
  272.     DisposeEventComparatorUPP       (EventComparatorUPP        userUPP);
  273.  
  274.     EXTERN_API(Boolean)
  275.     InvokeEventComparatorUPP       (EventRef                inEvent,
  276.                                     void *                    inCompareData,
  277.                                     EventComparatorUPP        userUPP);
  278.  
  279. #else
  280.     enum { uppEventComparatorProcInfo = 0x000003D0 };                 /* pascal 1_byte Func(4_bytes, 4_bytes) */
  281.     #define NewEventComparatorUPP(userRoutine)                         (EventComparatorUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppEventComparatorProcInfo, GetCurrentArchitecture())
  282.     #define DisposeEventComparatorUPP(userUPP)                         DisposeRoutineDescriptor(userUPP)
  283.     #define InvokeEventComparatorUPP(inEvent, inCompareData, userUPP)  (Boolean)CALL_TWO_PARAMETER_UPP((userUPP), uppEventComparatorProcInfo, (inEvent), (inCompareData))
  284. #endif
  285. /* support for pre-Carbon UPP routines: NewXXXProc and CallXXXProc */
  286. #define NewEventComparatorProc(userRoutine)                     NewEventComparatorUPP(userRoutine)
  287. #define CallEventComparatorProc(userRoutine, inEvent, inCompareData) InvokeEventComparatorUPP(inEvent, inCompareData, userRoutine)
  288. /*
  289.    PostEventToQueue retains the given event. You would normally release it after calling
  290.    this function.
  291. */
  292. EXTERN_API( OSStatus )
  293. PostEventToQueue                (EventRef                 inEvent,
  294.                                  EventPriority             inPriority);
  295.  
  296. EXTERN_API( Boolean )
  297. IsEventInQueue                    (EventRef                 inEvent);
  298.  
  299. EXTERN_API( OSStatus )
  300. FlushEventsMatchingListFromQueue (UInt32                 inNumTypes,
  301.                                  const EventTypeSpec *    inList);
  302.  
  303. EXTERN_API( OSStatus )
  304. FlushSpecificEventsFromQueue    (EventComparatorUPP     comparator,
  305.                                  void *                    compareData);
  306.  
  307. EXTERN_API( void )
  308. FlushEventQueue                    (void);
  309.  
  310. /*
  311.    Remove EventFromQueue removes the event from the event queue and releases it. If you
  312.    want to keep the event around, you should make sure to copy or retain it.
  313. */
  314.  
  315. EXTERN_API( void )
  316. RemoveEventFromQueue            (EventRef                 inEvent);
  317.  
  318. EXTERN_API( EventRef )
  319. FindSpecificEventInQueue        (EventComparatorUPP     comparator,
  320.                                  void *                    compareData);
  321.  
  322. EXTERN_API( UInt32 )
  323. GetNumEventsInQueue                (void);
  324.  
  325. /*--------------------------------------------------------------------------------------*/
  326. /*    o Helpful utilities                                                                    */
  327. /*--------------------------------------------------------------------------------------*/
  328. EXTERN_API( EventTime )
  329. GetCurrentEventTime                (void);
  330.  
  331. EXTERN_API( Boolean )
  332. IsUserCancelEventRef            (EventRef                 event);
  333.  
  334. EXTERN_API( OSStatus )
  335. TrackMouseLocation                (GrafPtr                 port, /* can be NULL */
  336.                                  Point *                outPt,
  337.                                  MouseTrackingResult *    result);
  338.  
  339. EXTERN_API( OSStatus )
  340. TrackMouseRegion                (GrafPtr                 port, /* can be NULL */
  341.                                  RgnHandle                 region,
  342.                                  Boolean *                wasInRgn,
  343.                                  MouseTrackingResult *    result);
  344.  
  345. EXTERN_API( Boolean )
  346. ConvertEventRefToEventRecord    (EventRef                 inEvent,
  347.                                  EventRecord *            outEvent);
  348.  
  349. EXTERN_API( Boolean )
  350. IsEventInMask                    (EventRef                 inEvent,
  351.                                  EventMask                 inMask);
  352.  
  353. EXTERN_API( EventTime )
  354. GetLastUserEventTime            (void);
  355.  
  356. /*--------------------------------------------------------------------------------------*/
  357. /*    o Timers                                                                            */
  358. /*--------------------------------------------------------------------------------------*/
  359. /* Timers, the new null processing mechanism.*/
  360. /* Not just good, but good for ya. */
  361.  
  362. typedef struct OpaqueEventLoopTimerRef*  EventLoopTimerRef;
  363. typedef CALLBACK_API( void , EventLoopTimerProcPtr )(EventLoopTimerRef inTimer, void *inUserData);
  364. typedef STACK_UPP_TYPE(EventLoopTimerProcPtr)                     EventLoopTimerUPP;
  365. #if OPAQUE_UPP_TYPES
  366.     EXTERN_API(EventLoopTimerUPP)
  367.     NewEventLoopTimerUPP           (EventLoopTimerProcPtr    userRoutine);
  368.  
  369.     EXTERN_API(void)
  370.     DisposeEventLoopTimerUPP       (EventLoopTimerUPP        userUPP);
  371.  
  372.     EXTERN_API(void)
  373.     InvokeEventLoopTimerUPP           (EventLoopTimerRef        inTimer,
  374.                                     void *                    inUserData,
  375.                                     EventLoopTimerUPP        userUPP);
  376.  
  377. #else
  378.     enum { uppEventLoopTimerProcInfo = 0x000003C0 };                 /* pascal no_return_value Func(4_bytes, 4_bytes) */
  379.     #define NewEventLoopTimerUPP(userRoutine)                         (EventLoopTimerUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppEventLoopTimerProcInfo, GetCurrentArchitecture())
  380.     #define DisposeEventLoopTimerUPP(userUPP)                         DisposeRoutineDescriptor(userUPP)
  381.     #define InvokeEventLoopTimerUPP(inTimer, inUserData, userUPP)     CALL_TWO_PARAMETER_UPP((userUPP), uppEventLoopTimerProcInfo, (inTimer), (inUserData))
  382. #endif
  383. /* support for pre-Carbon UPP routines: NewXXXProc and CallXXXProc */
  384. #define NewEventLoopTimerProc(userRoutine)                         NewEventLoopTimerUPP(userRoutine)
  385. #define CallEventLoopTimerProc(userRoutine, inTimer, inUserData) InvokeEventLoopTimerUPP(inTimer, inUserData, userRoutine)
  386. EXTERN_API( OSStatus )
  387. InstallEventLoopTimer            (EventTimerInterval     inFirstFire,
  388.                                  EventTimerInterval     inInterval,
  389.                                  EventLoopTimerUPP         inTimerProc,
  390.                                  void *                    inUserData,
  391.                                  EventLoopTimerRef *    outRef);
  392.  
  393. EXTERN_API( OSStatus )
  394. RemoveEventLoopTimer            (EventLoopTimerRef         inTimer);
  395.  
  396. EXTERN_API( OSStatus )
  397. SetEventLoopTimerNextFireTime    (EventLoopTimerRef         inTimer,
  398.                                  EventTimerInterval     nextFire);
  399.  
  400.  
  401. /*======================================================================================*/
  402. /*    EVENT CLASSES                                                                        */
  403. /*======================================================================================*/
  404. enum {
  405.     kEventClassMouse            = FOUR_CHAR_CODE('mous'),
  406.     kEventClassKeyboard            = FOUR_CHAR_CODE('keyb'),
  407.     kEventClassTextInput        = FOUR_CHAR_CODE('text'),
  408.     kEventClassApplication        = FOUR_CHAR_CODE('appl'),
  409.     kEventClassEPPC                = FOUR_CHAR_CODE('eppc'),
  410.     kEventClassMenu                = FOUR_CHAR_CODE('menu'),
  411.     kEventClassWindow            = FOUR_CHAR_CODE('wind'),
  412.     kEventClassControl            = FOUR_CHAR_CODE('cntl'),
  413.     kEventClassCommand            = FOUR_CHAR_CODE('cmds')
  414. };
  415.  
  416. /* Mouse Events */
  417. enum {
  418.     kEventLeftMouseDown            = 1,
  419.     kEventLeftMouseUp            = 2,
  420.     kEventRightMouseDown        = 3,
  421.     kEventRightMouseUp            = 4,
  422.     kEventMouseMoved            = 5,
  423.     kEventLeftMouseDragged        = 6,                            /* mouse moved while button down*/
  424.     kEventRightMouseDragged        = 7,
  425.     kEventMouseEntered            = 8,
  426.     kEventMouseExited            = 9,
  427.     kEventMouseWheelMoved        = 10                            /* placeholder. Not yet operational, unlike the new Death Star.*/
  428. };
  429.  
  430. enum {
  431.     kEventMouseButtonPrimary    = 0,                            /* only button for a one-button mouse (usually left button for multi-button mouse)*/
  432.     kEventMouseButtonSecondary    = 1,                            /* usually right button for a multi-button mouse*/
  433.     kEventMouseButtonTertiary    = 2                                /* usually middle button for a three-button mouse*/
  434. };
  435.  
  436. typedef UInt16                             EventMouseButton;
  437. enum {
  438.     kEventMouseWheelDirectionUp    = 0,
  439.     kEventMouseWheelDirectionDown = 1,
  440.     kEventMouseWheelDirectionLeft = 2,
  441.     kEventMouseWheelDirectionRight = 3
  442. };
  443.  
  444. typedef UInt16                             EventMouseWheelDirection;
  445. /* Keyboard Events */
  446. enum {
  447.     kEventRawKeyDown            = 1,                            /* hardware-level events*/
  448.     kEventRawKeyRepeat            = 2,
  449.     kEventRawKeyUp                = 3,
  450.     kEventRawKeyModifiersChanged = 4
  451. };
  452.  
  453. enum {
  454.     kEventTextInput                = 5                                /* high-level keyboard event (not available yet)*/
  455. };
  456.  
  457. /* Application Events */
  458. enum {
  459.     kEventAppActivated            = 1,                            /* resume, in old parlance*/
  460.     kEventAppDeactivated        = 2,                            /* suspend, in old parlance*/
  461.     kEventAppQuit                = 3,                            /* this app is quitting.*/
  462.     kEventAppLaunchNotification    = 4                                /* response to async application launch.*/
  463. };
  464.  
  465. /* Apple Events */
  466. enum {
  467.     kEventHighLevelEvent        = 1
  468. };
  469.  
  470.  
  471. /*
  472.       Window Refresh Events
  473.       
  474.       o kEventWindowUpdate
  475.           low-level update event.  You must call BeginUpdate, call SetPort,
  476.           draw your window content, and then call EndUpdate.
  477.       
  478.       o kEventWindowDrawContent
  479.           sent when the standard window handler sees an update event. 
  480.           BeginUpdate, SetPort, and EndUpdate are called for you; all you do
  481.           is draw.
  482.       
  483.       o kEventWindowDrawStructure
  484.           sent after the window manager has drawn the window frame.  The
  485.           current port is a global port clipped to the window structure
  486.           region, not the window's port.
  487.           
  488.       o kEventWindowEraseContent
  489.           called when the window manager wishes to erase the window
  490.           background (In ShowWindow, for example).  The current port is set
  491.           to the window's port.
  492.           
  493.       o kEventWindowActivate
  494.           window is active now
  495.           
  496.       o kEventWindowDeactivate
  497.           window is inactive now
  498. */
  499. enum {
  500.     kEventWindowUpdate            = 1,
  501.     kEventWindowDrawContent        = 2,
  502.     kEventWindowDrawStructure    = 3,
  503.     kEventWindowEraseContent    = 4,
  504.     kEventWindowActivate        = 5,
  505.     kEventWindowDeactivate        = 6
  506. };
  507.  
  508. /*
  509.       Window State Change Events
  510.       
  511.       o kEventWindowZOrderChanged
  512.           Sent after the window has changed position in the application
  513.           window list.
  514.       
  515.       o kEventWindowActivationChanged
  516.           Sent after the window has changed activation state (not currently
  517.           implemented)
  518.       
  519.       o kEventWindowOriginChange
  520.         kEventWindowSizeChange
  521.           Sent during ResizeWindow/DragWindow, before the window is
  522.           actually modified.  Alter the current bounds in the event to
  523.           change the intended location of the window.  "Origin"
  524.           indicates that the window's place location onscreen is
  525.           different.  "Size" indicates that the window's size has
  526.           changed (the origin may also be different).
  527.       
  528.       o kEventWindowOriginChanged
  529.         kEventWindowSizeChanged
  530.           Sent after the window has been resized or moved.
  531. */
  532.  
  533. enum {
  534.     kEventWindowZOrderChanged    = 16,
  535.     kEventWindowActivationChanged = 18,
  536.     kEventWindowOriginChange    = 20,
  537.     kEventWindowOriginChanged    = 21,
  538.     kEventWindowSizeChange        = 22,
  539.     kEventWindowSizeChanged        = 23
  540. };
  541.  
  542. /*
  543.       Window Click Events
  544.       
  545.       Low-level events which generate higher-level "action" events.
  546.       Most clients should allow the standard window handler to implement
  547.       these events.
  548.       
  549.       o kEventWindowClickDragRgn
  550.           sent when the mouse is down in the drag region.  Calls DragWindow.
  551.       
  552.       o kEventWindowClickResizeRgn
  553.           sent when the mouse is down in the resize area.  Calls ResizeWindow.
  554.       
  555.       o kEventWindowClickCollapseRgn
  556.           sent when the mouse is down in the collapse widget.  Generates
  557.           kEventWindowExpand or kEventWindowCollapse (whichever is the opposite
  558.           of the window's current collapse state).
  559.       
  560.       o kEventWindowClickCloseRgn
  561.           sent when the mouse is down in the close widget.  Generates
  562.           kEventWindowClose.
  563.       
  564.       o kEventWindowClickZoomRgn
  565.           sent when the mouse is down in the zoom widget.  Generates
  566.           kEventWindowZoom.     
  567.           
  568.       o kEventWindowClickContentRgn
  569.           sent when the mouse is down in the content region.
  570.       
  571.       o kEventWindowClickProxyIconRgn
  572.           sent when the mouse is down in the proxy icon.  Generates proxy
  573.           icon events.
  574. */
  575. enum {
  576.     kEventWindowClickDragRgn    = 32,
  577.     kEventWindowClickResizeRgn    = 33,
  578.     kEventWindowClickCollapseRgn = 34,
  579.     kEventWindowClickCloseRgn    = 35,
  580.     kEventWindowClickZoomRgn    = 36,
  581.     kEventWindowClickContentRgn    = 37,
  582.     kEventWindowClickProxyIconRgn = 38
  583. };
  584.  
  585. /*
  586.       Window Action Events
  587.       
  588.       o kEventWindowCollapse
  589.           If the window is not collapsed, this event is sent by the standard
  590.           window handler after it has received kEventWindowClickCollapseRgn
  591.           and received true from a call to TrackBox.  Standard window handler
  592.           calls CollapseWindow and then sends kEventWindowCollapsed if no
  593.           error is received from CollapseWindow.
  594.       
  595.       o kEventWindowCollapsed
  596.           Notification that the object has successfully collapsed.
  597.       
  598.       o kEventWindowCollapseAll
  599.           Sent by the standard window handler (when the option key is down)
  600.           after it has received kEventWindowClickCollapseRgn and then
  601.           received true from a call to TrackBox.  The standard window
  602.           handler's response is to send each window of the same class as the
  603.           clicked window a kEventWindowCollapse event.
  604.       
  605.       o kEventWindowExpand
  606.           If the window is collapsed, this event is sent by the standard
  607.           window handler after it has received kEventWindowClickCollapseRgn
  608.           and received true from a call to TrackBox.  The standard window
  609.           handler's response is to call CollapseWindow, then send
  610.           kEventWindowExpanded.
  611.       
  612.       o kEventWindowExpanded
  613.           Sent by the standard window handler (when the option key is down)
  614.           after it has received kEventWindowClickCollapseRgn and then
  615.           received true from a call to TrackBox.  The standard window
  616.           handler's response is to send each window of the same class as the
  617.           clicked window a kEventWindowExpand event.
  618.       
  619.       o kEventWindowExpandAll
  620.           Notification that the window has successfully expanded.
  621.       
  622.       o kEventWindowClose
  623.           Sent by the standard window handler after it has received
  624.           kEventWindowClickCloseRgn and successfully called TrackBox.
  625.       
  626.       o kEventWindowClosed
  627.           Dispatched by DisposeWindow before the object is disposed.
  628.       
  629.       o kEventWindowCloseAll
  630.           Sent by the standard window handler (when the option key is down)
  631.           after it has received kEventWindowClickCloseRgn and received true
  632.           from a call to TrackGoAway.  The standard window handler's response
  633.           is to send each window with the same class as the clicked window a
  634.           kEventWindowClose event.
  635.       
  636.       o kEventWindowZoom
  637.           Sent by the standard window handler upon receiving
  638.           kEventWindowClickZoomRgn and then receiving true from a call to
  639.           TrackBox.  The standard window handler's response is to zoom the
  640.           window using the sample code taken from the 8.5 Window Manager
  641.           documentation. Upon successful zoom, kEventWindowZoomed is sent.
  642.       
  643.       o kEventWindowZoomed
  644.           Notification that object has been successfully zoomed.
  645.       
  646.       o kEventWindowZoomAll
  647.           Sent by the standard window handler (when the option key is down)
  648.           after it has received kEventObjectClickZoomRgn and received true
  649.           from a call to TrackBox.  The standard window handler's response is
  650.           to send each window with the same class as the clicked window a
  651.           kEventObjectZoom event and then reposition all zoomed windows using
  652.           kCascadeOnParentWindowScreen.
  653.       
  654.       o kEventWindowContextualMenuSelect
  655.           Sent when either the right mouse button is pressed, or the control
  656.           key is held down and the left mouse button is pressed, or the left
  657.           mouse button is held down for more than 1/4th of a second (and
  658.           nothing else is handling the generated mouse tracking events).  
  659.           The standard window handler ignores this event.
  660.       
  661.       o kEventWindowPathSelect
  662.           Sent when IsWindowPathSelectClick would return true.  Set the
  663.           MenuRef in the event if you wish to customize the menu passed to
  664.           WindowPathSelect.
  665.       
  666.       o kEventWindowGetIdealSize
  667.           Sent by the standard window handler to determine the standard state
  668.           for zooming.  Set the mouse location of the event to the window's
  669.           ideal size.
  670.       
  671.       o kEventWindowProxyBeginDrag
  672.           Sent before a proxy icon drag; you can attach data to the DragRef
  673.           in the event.
  674.       
  675.       o kEventWindowProxyEndDrag
  676.           Sent after the proxy icon drag is complete, whether successful or
  677.           not.
  678. */
  679. enum {
  680.     kEventWindowCollapse        = 66,
  681.     kEventWindowCollapsed        = 67,
  682.     kEventWindowCollapseAll        = 68,
  683.     kEventWindowExpand            = 69,
  684.     kEventWindowExpanded        = 70,
  685.     kEventWindowExpandAll        = 71,
  686.     kEventWindowClose            = 72,
  687.     kEventWindowClosed            = 73,
  688.     kEventWindowCloseAll        = 74,
  689.     kEventWindowZoom            = 75,
  690.     kEventWindowZoomed            = 76,
  691.     kEventWindowZoomAll            = 77,
  692.     kEventWindowContextualMenuSelect = 78,
  693.     kEventWindowPathSelect        = 79,
  694.     kEventWindowGetIdealSize    = 80,
  695.     kEventWindowProxyBeginDrag    = 128,
  696.     kEventWindowProxyEndDrag    = 129
  697. };
  698.  
  699. /* Menu Events */
  700. enum {
  701.     kEventMenuBeginTracking        = 1,
  702.     kEventMenuEndTracking        = 2,
  703.     kEventMenuChangeTrackingMode = 3,
  704.     kEventMenuOpening            = 4,
  705.     kEventMenuClosed            = 5,
  706.     kEventMenuTargetItem        = 6,
  707.     kEventMenuMatchKey            = 7
  708. };
  709.  
  710. /* Command-related events */
  711. enum {
  712.     kEventProcessCommand        = 1
  713. };
  714.  
  715.  
  716. /* Control Events */
  717. enum {
  718.     kEventControlHit            = 1,
  719.     kEventControlSimulateHit    = 2
  720. };
  721.  
  722. /* HI Commands */
  723. enum {
  724.     kHICommandCancel            = FOUR_CHAR_CODE('not!'),        /* the most important command: cancel the current operation!  sent when the user presses command-period.*/
  725.     kHICommandQuit                = FOUR_CHAR_CODE('quit'),
  726.     kHICommandUndo                = FOUR_CHAR_CODE('undo'),
  727.     kHICommandRedo                = FOUR_CHAR_CODE('redo'),
  728.     kHICommandCut                = FOUR_CHAR_CODE('cut '),
  729.     kHICommandCopy                = FOUR_CHAR_CODE('copy'),
  730.     kHICommandPaste                = FOUR_CHAR_CODE('past'),
  731.     kHICommandClear                = FOUR_CHAR_CODE('clea'),
  732.     kHICommandSelectAll            = FOUR_CHAR_CODE('sall')
  733. };
  734.  
  735. enum {
  736.     kHICommandFromMenu            = (1L << 0)
  737. };
  738.  
  739.  
  740. struct HICommand {
  741.     UInt32                             attributes;
  742.     UInt32                             commandID;
  743.     struct {
  744.         MenuRef                         menuRef;
  745.         UInt16                             menuItemIndex;
  746.     }                                 menu;
  747. };
  748. typedef struct HICommand                HICommand;
  749. /*--------------------------------------------------------------------------------------*/
  750. /* Mouse Events                                                                            */
  751. /*--------------------------------------------------------------------------------------*/
  752.  
  753. EXTERN_API( EventRef )
  754. CreateMouseEvent                (UInt32                 kind,
  755.                                  EventTime                 when,
  756.                                  Point                     where,
  757.                                  UInt32                 modifiers);
  758.  
  759. EXTERN_API( OSStatus )
  760. SetMouseEventMouseLocation        (EventRef                 inEvent,
  761.                                  Point                     inPoint);
  762.  
  763. EXTERN_API( OSStatus )
  764. SetMouseEventKeyModifiers        (EventRef                 inEvent,
  765.                                  UInt32                 inModifiers);
  766.  
  767. EXTERN_API( OSStatus )
  768. SetMouseEventClickCount            (EventRef                 inEvent,
  769.                                  UInt32                 inCount);
  770.  
  771. EXTERN_API( OSStatus )
  772. GetMouseEventMouseLocation        (EventRef                 inEvent,
  773.                                  Point *                outPoint);
  774.  
  775. EXTERN_API( OSStatus )
  776. GetMouseEventKeyModifiers        (EventRef                 inEvent,
  777.                                  UInt32 *                outModifiers);
  778.  
  779. EXTERN_API( OSStatus )
  780. GetMouseEventClickCount            (EventRef                 inEvent,
  781.                                  UInt32 *                outCount);
  782.  
  783.  
  784. /*--------------------------------------------------------------------------------------*/
  785. /* Keyboard Events                                                                        */
  786. /*--------------------------------------------------------------------------------------*/
  787.  
  788. EXTERN_API( EventRef )
  789. CreateKeyboardEvent                (UInt32                 kind,
  790.                                  EventTime                 when,
  791.                                  UInt32                 inKeyChar,
  792.                                  UInt32                 inKeyCode,
  793.                                  UInt32                 inKeyModifiers);
  794.  
  795. EXTERN_API( OSStatus )
  796. SetKeyboardEventKeyCode            (EventRef                 inEvent,
  797.                                  UInt32                 inKeyCode);
  798.  
  799. EXTERN_API( OSStatus )
  800. SetKeyboardEventKeyChar            (EventRef                 inEvent,
  801.                                  UInt32                 inKeyChar);
  802.  
  803. EXTERN_API( OSStatus )
  804. SetKeyboardEventKeyModifiers    (EventRef                 inEvent,
  805.                                  UInt32                 inModifiers);
  806.  
  807. EXTERN_API( OSStatus )
  808. GetKeyboardEventKeyCode            (EventRef                 inEvent,
  809.                                  UInt32 *                outKeyCode);
  810.  
  811. EXTERN_API( OSStatus )
  812. GetKeyboardEventKeyChar            (EventRef                 inEvent,
  813.                                  UInt32 *                outKeyChar);
  814.  
  815. EXTERN_API( OSStatus )
  816. GetKeyboardEventKeyModifiers    (EventRef                 inEvent,
  817.                                  UInt32 *                outModifiers);
  818.  
  819. /*--------------------------------------------------------------------------------------*/
  820. /* Window Events                                                                        */
  821. /*--------------------------------------------------------------------------------------*/
  822. EXTERN_API( EventRef )
  823. CreateWindowEvent                (UInt32                 kind,
  824.                                  EventTime                 when,
  825.                                  WindowRef                 window);
  826.  
  827. EXTERN_API( OSStatus )
  828. SetWindowEventWindowRef            (EventRef                 inEvent,
  829.                                  WindowRef                 inWindow);
  830.  
  831. EXTERN_API( OSStatus )
  832. SetWindowEventKeyModifiers        (EventRef                 inEvent,
  833.                                  UInt32                 inModifiers);
  834.  
  835. EXTERN_API( OSStatus )
  836. SetWindowEventMouseLocation        (EventRef                 inEvent,
  837.                                  Point                     inWhere);
  838.  
  839. EXTERN_API( OSStatus )
  840. GetWindowEventWindowRef            (EventRef                 inEvent,
  841.                                  WindowRef *            outWindow);
  842.  
  843. EXTERN_API( OSStatus )
  844. GetWindowEventKeyModifiers        (EventRef                 inEvent,
  845.                                  UInt32 *                outModifiers);
  846.  
  847. EXTERN_API( OSStatus )
  848. GetWindowEventMouseLocation        (EventRef                 inEvent,
  849.                                  Point *                outWhere);
  850.  
  851. /* window proxy events*/
  852. EXTERN_API( OSStatus )
  853. GetWindowEventDragRef            (EventRef                 eventRef,
  854.                                  DragRef *                outDrag);
  855.  
  856. EXTERN_API( OSStatus )
  857. SetWindowEventDragRef            (EventRef                 eventRef,
  858.                                  DragRef                 inDrag);
  859.  
  860. EXTERN_API( OSStatus )
  861. GetWindowEventMenuRef            (EventRef                 eventRef,
  862.                                  MenuRef *                outMenu);
  863.  
  864. EXTERN_API( OSStatus )
  865. SetWindowEventMenuRef            (EventRef                 eventRef,
  866.                                  MenuRef                 inMenu);
  867.  
  868. /* window bounds-changed events*/
  869. EXTERN_API( OSStatus )
  870. GetWindowEventOriginalBounds    (EventRef                 eventRef,
  871.                                  Rect *                    outBounds);
  872.  
  873. EXTERN_API( OSStatus )
  874. SetWindowEventOriginalBounds    (EventRef                 eventRef,
  875.                                  const Rect *            inBounds);
  876.  
  877. EXTERN_API( OSStatus )
  878. GetWindowEventPreviousBounds    (EventRef                 eventRef,
  879.                                  Rect *                    outBounds);
  880.  
  881. EXTERN_API( OSStatus )
  882. SetWindowEventPreviousBounds    (EventRef                 eventRef,
  883.                                  const Rect *            inBounds);
  884.  
  885. EXTERN_API( OSStatus )
  886. GetWindowEventCurrentBounds        (EventRef                 eventRef,
  887.                                  Rect *                    outBounds);
  888.  
  889. EXTERN_API( OSStatus )
  890. SetWindowEventCurrentBounds        (EventRef                 eventRef,
  891.                                  const Rect *            inBounds);
  892.  
  893. /*
  894.    window refresh events (except kEventWindowUpdate) contain the grafport which you should be drawing into;
  895.    the current grafport is set to this port.
  896. */
  897. EXTERN_API( OSStatus )
  898. GetWindowEventGrafPort            (EventRef                 eventRef,
  899.                                  GrafPtr *                outPort);
  900.  
  901. EXTERN_API( OSStatus )
  902. SetWindowEventGrafPort            (EventRef                 eventRef,
  903.                                  GrafPtr                 inPort);
  904.  
  905. /* window click events each contain a reference to the original mouse down event*/
  906. EXTERN_API( OSStatus )
  907. GetWindowEventMouseEvent        (EventRef                 eventRef,
  908.                                  EventRef *                outEvent);
  909.  
  910. EXTERN_API( OSStatus )
  911. SetWindowEventMouseEvent        (EventRef                 eventRef,
  912.                                  EventRef                 inEvent);
  913.  
  914.  
  915. /*--------------------------------------------------------------------------------------*/
  916. /* Control Events                                                                        */
  917. /*--------------------------------------------------------------------------------------*/
  918. EXTERN_API( EventRef )
  919. CreateControlEvent                (UInt32                 kind,
  920.                                  EventTime                 when,
  921.                                  ControlRef             control);
  922.  
  923. EXTERN_API( OSStatus )
  924. SetControlEventControlRef        (EventRef                 inEvent,
  925.                                  ControlRef             inControl);
  926.  
  927. EXTERN_API( OSStatus )
  928. SetControlEventControlPartCode    (EventRef                 inEvent,
  929.                                  ControlPartCode         inPart);
  930.  
  931. EXTERN_API( OSStatus )
  932. SetControlEventKeyModifiers        (EventRef                 inEvent,
  933.                                  UInt32                 inModifiers);
  934.  
  935. EXTERN_API( OSStatus )
  936. GetControlEventControlRef        (EventRef                 inEvent,
  937.                                  ControlRef *            outControl);
  938.  
  939. EXTERN_API( OSStatus )
  940. GetControlEventControlPartCode    (EventRef                 inEvent,
  941.                                  ControlPartCode *        outPart);
  942.  
  943. EXTERN_API( OSStatus )
  944. GetControlEventKeyModifiers        (EventRef                 inEvent,
  945.                                  UInt32 *                outModifiers);
  946.  
  947. /*--------------------------------------------------------------------------------------*/
  948. /* Menu Events                                                                            */
  949. /*--------------------------------------------------------------------------------------*/
  950. EXTERN_API( EventRef )
  951. CreateMenuEvent                    (UInt32                 kind,
  952.                                  EventTime                 when,
  953.                                  MenuRef                 menu);
  954.  
  955. EXTERN_API( OSStatus )
  956. SetMenuEventMenuRef                (EventRef                 inEvent,
  957.                                  MenuRef                 inMenu);
  958.  
  959. EXTERN_API( OSStatus )
  960. SetMenuEventTrackingMode        (EventRef                 inEvent,
  961.                                  MenuTrackingMode         inMode,
  962.                                  Boolean                 setCurrent);
  963.  
  964. EXTERN_API( OSStatus )
  965. SetMenuEventFirstTimeOpen        (EventRef                 inEvent,
  966.                                  Boolean                 inFirstTimeOpen);
  967.  
  968. EXTERN_API( OSStatus )
  969. SetMenuEventItemIndex            (EventRef                 inEvent,
  970.                                  MenuItemIndex             inItemIndex);
  971.  
  972. EXTERN_API( OSStatus )
  973. SetMenuEventCommandID            (EventRef                 inEvent,
  974.                                  MenuCommand             inCommand);
  975.  
  976. EXTERN_API( OSStatus )
  977. SetMenuEventKeyEvent            (EventRef                 inEvent,
  978.                                  EventRef                 inKeyEvent);
  979.  
  980. EXTERN_API( OSStatus )
  981. SetMenuEventHICommand            (EventRef                 inEvent,
  982.                                  const HICommand *        inCommand);
  983.  
  984. EXTERN_API( OSStatus )
  985. GetMenuEventMenuRef                (EventRef                 inEvent,
  986.                                  MenuRef *                outMenu);
  987.  
  988. EXTERN_API( OSStatus )
  989. GetMenuEventTrackingMode        (EventRef                 inEvent,
  990.                                  Boolean                 getCurrent,
  991.                                  MenuTrackingMode *        outMode);
  992.  
  993. EXTERN_API( OSStatus )
  994. GetMenuEventFirstTimeOpen        (EventRef                 inEvent,
  995.                                  Boolean *                outFirstTimeOpen);
  996.  
  997. EXTERN_API( OSStatus )
  998. GetMenuEventItemIndex            (EventRef                 inEvent,
  999.                                  MenuItemIndex *        outItemIndex);
  1000.  
  1001. EXTERN_API( OSStatus )
  1002. GetMenuEventCommandID            (EventRef                 inEvent,
  1003.                                  MenuCommand *            outCommand);
  1004.  
  1005. EXTERN_API( OSStatus )
  1006. GetMenuEventKeyEvent            (EventRef                 inEvent,
  1007.                                  EventRef *                outKeyEvent);
  1008.  
  1009. EXTERN_API( OSStatus )
  1010. GetMenuEventHICommand            (EventRef                 inEvent,
  1011.                                  HICommand *            outCommand);
  1012.  
  1013. /*--------------------------------------------------------------------------------------*/
  1014. /* Command Events                                                                        */
  1015. /*--------------------------------------------------------------------------------------*/
  1016.  
  1017. EXTERN_API( EventRef )
  1018. CreateCommandEvent                (UInt32                 kind,
  1019.                                  EventTime                 when,
  1020.                                  const HICommand *        inCommand);
  1021.  
  1022. EXTERN_API( OSStatus )
  1023. GetCommandEventCommand            (EventRef                 inEvent,
  1024.                                  HICommand *            outCommand);
  1025.  
  1026. /*--------------------------------------------------------------------------------------*/
  1027. /* Miscellany                                                                            */
  1028. /*--------------------------------------------------------------------------------------*/
  1029.  
  1030. EXTERN_API( EventRef )
  1031. CreateApplicationEvent            (UInt32                 kind,
  1032.                                  EventTime                 when);
  1033.  
  1034.  
  1035. /*
  1036.    This routine is used to get information about an async application launch
  1037.    It is only valid on Mac OS X.
  1038. */
  1039.  
  1040. EXTERN_API( OSStatus )
  1041. GetApplicationEventLaunchData    (EventRef                 event,
  1042.                                  OSStatus *                outLaunchErr,
  1043.                                  ProcessSerialNumber *    outProcess,
  1044.                                  void **                outLaunchRefCon);
  1045.  
  1046. /*======================================================================================*/
  1047. /*    EVENT HANDLERS                                                                        */
  1048. /*======================================================================================*/
  1049.  
  1050. typedef UInt32 EventHandlerResult;
  1051. enum {
  1052.     kEventHandlerHandled        = 0,
  1053.     kEventHandlerNotHandled        = 1,
  1054.     kEventHandlerPassUpChain    = 2,
  1055.     kEventHandlerStopProcessing    = 3
  1056. };
  1057.  
  1058.  
  1059. enum {
  1060.     kEventHandlerStandard        = -1L
  1061. };
  1062.  
  1063.  
  1064.  
  1065.  
  1066. typedef struct OpaqueEventHandlerRef*     EventHandlerRef;
  1067.  
  1068. /*--------------------------------------------------------------------------------------*/
  1069. /*    o EventHandler specification                                                        */
  1070. /*--------------------------------------------------------------------------------------*/
  1071.  
  1072. typedef CALLBACK_API( EventHandlerResult , EventHandlerProcPtr )(EventHandlerRef inHandlerRef, EventRef inEvent, void *userData);
  1073. typedef STACK_UPP_TYPE(EventHandlerProcPtr)                     EventHandlerUPP;
  1074. #if OPAQUE_UPP_TYPES
  1075.     EXTERN_API(EventHandlerUPP)
  1076.     NewEventHandlerUPP               (EventHandlerProcPtr        userRoutine);
  1077.  
  1078.     EXTERN_API(void)
  1079.     DisposeEventHandlerUPP           (EventHandlerUPP            userUPP);
  1080.  
  1081.     EXTERN_API(EventHandlerResult)
  1082.     InvokeEventHandlerUPP           (EventHandlerRef            inHandlerRef,
  1083.                                     EventRef                inEvent,
  1084.                                     void *                    userData,
  1085.                                     EventHandlerUPP            userUPP);
  1086.  
  1087. #else
  1088.     enum { uppEventHandlerProcInfo = 0x00000FF0 };                     /* pascal 4_bytes Func(4_bytes, 4_bytes, 4_bytes) */
  1089.     #define NewEventHandlerUPP(userRoutine)                         (EventHandlerUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppEventHandlerProcInfo, GetCurrentArchitecture())
  1090.     #define DisposeEventHandlerUPP(userUPP)                         DisposeRoutineDescriptor(userUPP)
  1091.     #define InvokeEventHandlerUPP(inHandlerRef, inEvent, userData, userUPP)  (EventHandlerResult)CALL_THREE_PARAMETER_UPP((userUPP), uppEventHandlerProcInfo, (inHandlerRef), (inEvent), (userData))
  1092. #endif
  1093. /* support for pre-Carbon UPP routines: NewXXXProc and CallXXXProc */
  1094. #define NewEventHandlerProc(userRoutine)                         NewEventHandlerUPP(userRoutine)
  1095. #define CallEventHandlerProc(userRoutine, inHandlerRef, inEvent, userData) InvokeEventHandlerUPP(inHandlerRef, inEvent, userData, userRoutine)
  1096. /*--------------------------------------------------------------------------------------*/
  1097. /*    o Installing Event Handlers                                                            */
  1098. /*                                                                                        */
  1099. /* Use these routines to install event handlers for a specific toolbox object. You may    */
  1100. /* pass zero for inNumTypes and NULL for inList if you need to be in a situation where    */
  1101. /* you know you will be receiving events, but not exactly which ones at the time you    */
  1102. /* are installing the handler. Later, your application can call the Add/Remove routines    */
  1103. /* listed below this section.                                                            */
  1104. /*                                                                                        */
  1105. /* You can only install a specific handler once. The combination of inHandler and        */
  1106. /* inUserData is considered the 'signature' of a handler. Any attempt to install a new    */
  1107. /* handler with the same proc and user data as an already-installed handler will result    */
  1108. /* in eventHandlerAlreadyInstalledErr. Installing the same proc and user data on a         */
  1109. /* different object is legal.                                                            */
  1110. /*                                                                                        */
  1111. /* Upon successful completion of this routine, you are returned an EventHandlerRef,     */
  1112. /* which you can use in various other calls, and is passed to your event handler. You    */
  1113. /* use it to extract information about the handler, such as the target (window, etc.)    */
  1114. /* if you have the same handler installed for different objects and need to perform        */
  1115. /* actions on the current target (say, call a window manager function).                    */
  1116. /*--------------------------------------------------------------------------------------*/
  1117. EXTERN_API( OSStatus )
  1118. InstallApplicationEventHandler    (EventHandlerUPP         inHandler,
  1119.                                  UInt32                 inNumTypes,
  1120.                                  const EventTypeSpec *    inList,
  1121.                                  void *                    inUserData,
  1122.                                  EventHandlerRef *        outRef);
  1123.  
  1124. EXTERN_API( OSStatus )
  1125. InstallWindowEventHandler        (WindowRef                 inWindowRef,
  1126.                                  EventHandlerUPP         inHandler,
  1127.                                  UInt32                 inNumTypes,
  1128.                                  const EventTypeSpec *    inList,
  1129.                                  void *                    inUserData,
  1130.                                  EventHandlerRef *        outRef);
  1131.  
  1132. EXTERN_API( OSStatus )
  1133. InstallControlEventHandler        (ControlRef             inControlRef,
  1134.                                  EventHandlerUPP         inHandler,
  1135.                                  UInt32                 inNumTypes,
  1136.                                  const EventTypeSpec *    inList,
  1137.                                  void *                    inUserData,
  1138.                                  EventHandlerRef *        outRef);
  1139.  
  1140. EXTERN_API( OSStatus )
  1141. InstallMenuEventHandler            (MenuRef                 inMenuRef,
  1142.                                  EventHandlerUPP         inHandler,
  1143.                                  UInt32                 inNumTypes,
  1144.                                  const EventTypeSpec *    inList,
  1145.                                  void *                    inUserData,
  1146.                                  EventHandlerRef *        outRef);
  1147.  
  1148. EXTERN_API( OSStatus )
  1149. RemoveEventHandler                (EventHandlerRef         inHandlerRef);
  1150.  
  1151. /*--------------------------------------------------------------------------------------*/
  1152. /*    o Adjusting set of event types after a handler is created                            */
  1153. /*                                                                                        */
  1154. /* After installing a handler with the routine above, you can adjust the event type        */
  1155. /* list telling the toolbox what events to send to that handler by calling the two        */
  1156. /* routines below. If you add an event type twice for the same handler, your handler    */
  1157. /* will only be called once, but it will take two RemoveEventType calls to stop your    */
  1158. /* handler from being called with that event type. In other words, the install count    */
  1159. /* for each event type is maintained by the toolbox. This might allow you, for example    */
  1160. /* to have subclasses of a window object register for types without caring if the base    */
  1161. /* class has already registered for that type. When the subclass removes its types, it     */
  1162. /* can succesfully do so without affecting the base class' reception of its events        */
  1163. /* types, yielding eternal bliss.                                                        */
  1164. /*--------------------------------------------------------------------------------------*/
  1165.  
  1166. EXTERN_API( OSStatus )
  1167. AddEventTypesToHandler            (EventHandlerRef         inHandlerRef,
  1168.                                  UInt32                 inNumTypes,
  1169.                                  const EventTypeSpec *    inList);
  1170.  
  1171. EXTERN_API( OSStatus )
  1172. RemoveEventTypesFromHandler        (EventHandlerRef         inHandlerRef,
  1173.                                  UInt32                 inNumTypes,
  1174.                                  const EventTypeSpec *    inList);
  1175.  
  1176. /*--------------------------------------------------------------------------------------*/
  1177. /*    o Explicit Propogation                                                                */
  1178. /*--------------------------------------------------------------------------------------*/
  1179.  
  1180. EXTERN_API( EventHandlerResult )
  1181. CallNextEventHandler            (EventHandlerRef         inThisHandler,
  1182.                                  EventRef                 inEvent);
  1183.  
  1184. /*--------------------------------------------------------------------------------------*/
  1185. /*    o Getting the target from a handler ref                                                */
  1186. /*--------------------------------------------------------------------------------------*/
  1187.  
  1188. EXTERN_API( ControlRef )
  1189. GetEventHandlerTargetControl    (EventHandlerRef         inHandler);
  1190.  
  1191. EXTERN_API( WindowRef )
  1192. GetEventHandlerTargetWindow        (EventHandlerRef         inHandler);
  1193.  
  1194. EXTERN_API( MenuRef )
  1195. GetEventHandlerTargetMenu        (EventHandlerRef         inHandler);
  1196.  
  1197. /*--------------------------------------------------------------------------------------*/
  1198. /*    o Sending Events                                                                    */
  1199. /*--------------------------------------------------------------------------------------*/
  1200.  
  1201. EXTERN_API( EventHandlerResult )
  1202. SendEventToApplication            (EventRef                 inEvent);
  1203.  
  1204. EXTERN_API( EventHandlerResult )
  1205. SendEventToWindow                (EventRef                 inEvent,
  1206.                                  WindowRef                 inWindow);
  1207.  
  1208. EXTERN_API( EventHandlerResult )
  1209. SendEventToControl                (EventRef                 inEvent,
  1210.                                  ControlRef             inControl);
  1211.  
  1212. EXTERN_API( EventHandlerResult )
  1213. SendEventToMenu                    (EventRef                 inEvent,
  1214.                                  MenuRef                 inMenu);
  1215.  
  1216. EXTERN_API( EventHandlerResult )
  1217. SendEventToUserFocus            (EventRef                 inEvent);
  1218.  
  1219. /*--------------------------------------------------------------------------------------*/
  1220. /*    o Command Routines                                                                    */
  1221. /*--------------------------------------------------------------------------------------*/
  1222.  
  1223. EXTERN_API( EventHandlerResult )
  1224. ProcessHICommand                (const HICommand *        inCommand);
  1225.  
  1226. /*--------------------------------------------------------------------------------------*/
  1227. /*    o Event Loop Routines                                                                */
  1228. /*--------------------------------------------------------------------------------------*/
  1229.  
  1230. EXTERN_API( void )
  1231. RunApplicationEventLoop            (void);
  1232.  
  1233. EXTERN_API( void )
  1234. QuitApplicationEventLoop        (void);
  1235.  
  1236. /*--------------------------------------------------------------------------------------*/
  1237. /*    o User Focus                                                                        */
  1238. /*--------------------------------------------------------------------------------------*/
  1239.  
  1240. EXTERN_API( void )
  1241. SetUserFocusWindow                (WindowRef                 inWindow);
  1242.  
  1243. EXTERN_API( WindowRef )
  1244. GetUserFocusWindow                (void);
  1245.  
  1246.  
  1247. /*--------------------------------------------------------------------------------------*/
  1248. /*    o Default/Cancel buttons                                                            */
  1249. /*--------------------------------------------------------------------------------------*/
  1250.  
  1251. EXTERN_API( OSStatus )
  1252. SetWindowDefaultButton            (WindowRef                 inWindow,
  1253.                                  ControlRef             inControl) /* can be NULL */;
  1254.  
  1255. EXTERN_API( OSStatus )
  1256. SetWindowCancelButton            (WindowRef                 inWindow,
  1257.                                  ControlRef             inControl) /* can be NULL */;
  1258.  
  1259. EXTERN_API( OSStatus )
  1260. GetWindowDefaultButton            (WindowRef                 inWindow,
  1261.                                  ControlRef *            outControl);
  1262.  
  1263. EXTERN_API( OSStatus )
  1264. GetWindowCancelButton            (WindowRef                 inWindow,
  1265.                                  ControlRef *            outControl);
  1266.  
  1267.  
  1268. #if PRAGMA_STRUCT_ALIGN
  1269.     #pragma options align=reset
  1270. #elif PRAGMA_STRUCT_PACKPUSH
  1271.     #pragma pack(pop)
  1272. #elif PRAGMA_STRUCT_PACK
  1273.     #pragma pack()
  1274. #endif
  1275.  
  1276. #ifdef PRAGMA_IMPORT_OFF
  1277. #pragma import off
  1278. #elif PRAGMA_IMPORT
  1279. #pragma import reset
  1280. #endif
  1281.  
  1282. #ifdef __cplusplus
  1283. }
  1284. #endif
  1285.  
  1286. #endif /* __CARBONEVENTS__ */
  1287.  
  1288.